---
layout: docs
page_title: Agent
description: The Nomad Autoscaler is a long lived process which coordinates scaling activates.
---

# Nomad Autoscaler Agent

The Nomad Autoscaler agent has a variety of parameters that can be specified
via configuration files or command-line flags. Configuration files are written
in [HCL][hcl_v2]. The Nomad Autoscaler can read and combine parameters from
multiple configuration files or directories to configure the agent.

## Nomad Namespaces

You can configure Nomad Autoscaler to use a [Nomad namespace][nomad_namespaces]
using the agent's [`nomad`][autoscaler_agent_nomad] configuration block. The
Autoscaler retrieves scaling policies and perform autoscaling only for jobs in
that namespace. If you use the special wildcard namespace value `*`, the
Autoscaler agent retrieves scaling policies from all namespaces. A future
version will include support for multiple namespaces.

## Nomad ACLs

The Nomad Autoscaler can be configured to interact with an ACL-enabled Nomad
cluster. Nomad includes the `scale` ACL policy disposition specifically for
supporting the operations of the Nomad Autoscaler. Therefore, the
following policy is sufficient for creating an ACL token that can be used by
the autoscaler for fetching scaling policies and scaling jobs:

```hcl
namespace "default" {
  policy = "scale"
}
```

When utilizing the High-Availability feature added in v0.4.0, the ACL policy
needs to include capabilities that allow the Nomad Autoscaler to obtain and release Nomad variable
locks. The namespace identifier should match the configured
[`high_availability.lock_namespace`][autoscaler_ha_lock_namespace] parameter,
and the path should match the [`high_availability.lock_path`][autoscaler_ha_lock_path]
parameter.

```hcl
namespace "default" {
  variables {
    path "nomad-autoscaler/lock" {
      capabilities = ["write"]
    }
  }
}
```

If running Nomad Autoscaler Enterprise, the following ACL policy addition is
needed to ensure it can read the Nomad Enterprise license.

```hcl
operator {
  policy = "read"
}
```

Other APM and target plugins may require additional ACLs; see the plugin documentation for more information.

## Load Order and Merging

The Nomad Autoscaler agent supports multiple configuration files, which can be
provided using the [`-config`][autoscaler_cli_config] CLI flag. The flag can
accept either a file or folder. In the case of a folder, any `.hcl` and `.json`
files in the folder will be loaded and merged in lexicographical order. Directories
are not loaded recursively.

For example:

```shell-session
$ nomad-autoscaler agent -config=autoscaler.hcl -config=/etc/nomad-autoscaler -config=extra.json
```

This will load configuration from `autoscaler.hcl`, from `.hcl` and `.json` files
under `/etc/nomad-autoscaler`, and finally from `extra.json`. As each file is
processed, its contents are merged into the existing configuration. When merging,
any non-empty values from the latest config file will append or replace
parameters in the current configuration. An empty value means `""` for strings,
`0` for integer or float values, and `false` for booleans.

## SIGHUP Reload

The Nomad Autoscaler agent supports handling the `SIGHUP` signal for reloading without the need for
restarting the agent. When sending a `SIGHUP` signal to the agent process, the agent will perform the
following actions.

- reload the contents of the scaling policy directory as defined by the [`-policy-dir`][autoscaler_cli_policy_dir]
  parameter.

- reconfigure the Nomad clients used to fetch policies and execute scaling
  actions with the values defined in the [`nomad`][autoscaler_agent_nomad]
  block.

- stop plugins that are no longer present in the configuration file.

- start plugins that were not previously present in the configuration file.

- reconfigure the remaining plugins with the configuration defined in their
  `config` parameter.

## General Parameters

- `enable_debug` `(bool: false)` - Specifies if the debugging HTTP endpoints
  should be enabled. These endpoints can be used with profiling tools to dump
  diagnostic information about the Nomad Autoscaler's internals.

- `log_level` `(string: "INFO")` - Specify the verbosity level of Nomad
  Autoscaler's logs. Valid values include DEBUG, INFO, and WARN, in decreasing
  order of verbosity.

- `log_json` `(bool: false)` - Output logs in a JSON format.

- `plugin_dir` `(string: "./plugins")` - The plugin directory is used to
  discover Nomad Autoscaler plugins.

[hcl_v2]: https://github.com/hashicorp/hcl/tree/hcl2
[nomad_namespaces]: /nomad/docs/govern/namespaces
[nomad_acls]: /nomad/tutorials/access-control
[autoscaler_agent_nomad]: /nomad/tools/autoscaling/agent/nomad
[autoscaler_cli_config]: /nomad/tools/autoscaling/cli#config
[autoscaler_cli_policy_dir]: /nomad/tools/autoscaling/cli#policy-dir
[autoscaler_ha_lock_namespace]: /nomad/tools/autoscaling/agent/high_availability#lock_namespace
[autoscaler_ha_lock_path]: /nomad/tools/autoscaling/agent/high_availability#lock_path
